home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Celestin Apprentice 5
/
Apprentice-Release5.iso
/
Source Code
/
Libraries
/
Bitmap Libraries 2.0
/
BitMap.txt
< prev
Wrap
Text File
|
1996-07-08
|
47KB
|
1,493 lines
file BitMap.txt Copyright (C) 1996 by John Montbriand. All Rights Reserved.
ABOUT BITMAP...
Copyright (C) 1996 by John Montbriand. All Rights Reserved.
Distribute freely in areas where the laws of copyright apply.
Use at your own risk.
Do not distribute modified copies.
These various BitMap libraries are for free!
ABOUT THE AUTHOR...
Comments, questions, or suggestions are always welcome.
John Montbriand tinyjohn@sasknet.sk.ca
P.O. Box. 1133
Saskatoon Saskatchewan Canada
S7K 3N2
WHY IS IT FOR FREE?
none of your business,
but if you have some business for me, I'll see what I can do..
OUTLINE OF TOPICS
BITMAPS, WHAT ARE THEY?
IMPLEMENTATION NOTES
MATERIALS
LEGAL STUFF
FURTHER REFERENCE
SERVICES PROVIDED (OVERVIEW)
BE CAREFUL (CAVEATS)
OTHER COOL THINGS YOU CAN DO
OVERVIEW OF ROUTINES
SPECIFIC ROUTINE DESCRIPTIONS
BITMAPS, WHAT ARE THEY?
Well, they're like little black and white computer screens in memory
that you can do drawing in before transfering the images you
draw on them to the screen. Drawing things off screen and then
placing them on screen creates the feel of instantaneous, flicker
free drawing.
BitMaps are a data structure used to store black and white images
off-screen. You can use quickdraw to draw directly into bitmaps
and create images for placement on the screen, or you can take
images from the screen, place them in a bitmap, do various
transformations to them, and then put them back on the screen.
QuickDraw GrafPorts draw into BitMap structures, and, as a matter
of fact, all screen drawing on early macintoshes was implemented
through BitMaps that were memory mapped to the screen hardware.
The big advantage: BitMaps provide a way to do simple high quality
graphics while at the same time requiring very little memory.
IMPLEMENTATION NOTES
This implementation stores each bitmap in a single, contiguous,
non-relocatable memory block refered to using a pointer. The first
14 bytes of the memory block contain the Bitmap data structure,
while the remaining bytes are used to store the raster data.
MATERIALS
The BitMap format itself is the copyright property of Apple
computer and has been known to the public since 1983.
The routines documented herein are the copyright property of
John Montbriand. I am making these routines available to the
macintosh programming community because I feel it's about time
someone did! They're fun, easy to use, and practical. I hope
all who find them will use them well.
Compiled and tested with MPW C, MWC, SC, MrC, and MPW PPC.
LEGAL STUFF
These libraries are provided for free and you may use them
in any program you make; however, if you're particular about
having signed documentation that proves this fact in your posession
then, as I would like to ensure these libraries are widely used,
I would be glad provide such documents for you.
I don't think this is entirly necessary, but I can understand
that some folks feel quite strongly about such issues and prefer
to do things in writing.
If you would like for me to send you a signed document saying
that you have license to use these routines in your programs,
then send me a couple of bucks to cover postage and handling
and I'll send you back a signed letter saying you have license
to use these routines in any software you make.
I think two or three dollars is fair as I don't really get a big
thrill out of printing stuff out and mailing it, and that's usually
enough to cover postage to anywhere in the world. I s'pose you'd have
to figure out how much it would cost for me to mail a letter to you
from here in Canada.
FURTHER REFERENCE
BitMap.h and BitMap.c contain routines for accessing and manipulating
BitMap data stored in pointers. For more information about BitMaps,
offscreen drawing, pointers, C, etc.. refer to the following sources:
"Bitmaps" (2-9) in the "Basic QuickDraw" chapter of Inside Macintosh:
Imaging With QuickDraw by Apple Computer, Inc. Addison-Wesley.
A discussion of the Bitmap data structure and how it applies to
GrafPorts.
"Boolean Transfer Modes With 1-Bit Pixels" (3-8) in the "QuickDraw Drawing"
chapter of Inside Macintosh: Imaging With QuickDraw by Apple Computer,
Inc. Addison-Wesley.
BitMaps are 1-Bit Pixel data structures. This part discusses the
various transfer modes you can use while drawing into BitMaps.
"Copying Bits Between Graphics Ports" (3-32) in the "QuickDraw Drawing"
chapter of Inside Macintosh: Imaging With QuickDraw by Apple
Computer, Inc. Addison-Wesley.
A discussion of the Bitmap data structure and how it applies to
GrafPorts.
"Copying Images" (3-112) in the "QuickDraw Drawing" chapter of
Inside Macintosh: Imaging With QuickDraw by Apple
Computer, Inc. Addison-Wesley.
A discussion of the CopyBits routine and the various parameter
combinations you can use with it. This is followed by
a discussion of the CopyMask routine.
Technical note #163 "Adding Color With CopyBits" by Chris Derossi
A discussion of how to draw in colour using bitmaps.
Technical note #193 "So Many Bitmaps, So Little Time" by Rick Blair
A look at the BitMapToRegion routine.
Technical note #41 "Drawing Into an Offscreen Bitmap" by
Jim Friedlander & Ginger Jernigan
A talk about offscreen bitmaps, and how to use them.
Inside Macintosh: Memory by Apple Computer, Inc. Addison-Wesley.
A discussion of memory managment, pointers, what they are, and
how to use them.
The C Programming Language 2nd edition by Brian W. Kernighan
and Dennis M. Ritchie. Prentice Hall.
Comments for the routines provided herein have been included in the
file BitMap.h.
Also, there is a 411 help file.
SERVICES PROVIDED (OVERVIEW)
- routines for creating bitmap structures in memory.
- rotate functions for rotating bitmaps 90 degrees left and right,
- flip functions for flipping bitmap data both vertically
and horizontally,
- a trace edges routine for tracing the edges of an image,
- a rotation routine for rotating a bitmap to a particular angle,
- a routine for duplicating bitmaps,
- a routine for comparing bitmaps,
- routines providing the painbucket tool and lasso tool effects,
- transfer routines for transfering bitmap data to and from the
PICT format,
- a complete set of logical operations on bitmaps,
- a complete set of pixel oriented routines for testing, setting,
clearing, and toggling individual pixels in bitmaps,
- routines and a macro allowing you to quickly and easily draw
into bitmaps,
- routines for copying bitmap images to the current grafport,
BE CAREFUL (CAVEATS)
I think these routines are safe to use, but you should do your own
testing. I have provided the source code, and if you find any bugs,
please let me know right away so I can provide corrections in
future versions.
I advertise a finder's fee of $10.00 cash for errors in any
of my products.
OTHER COOL THINGS YOU CAN DO
bitmaps provide a convenient, storage efficient way to
implement zero - one adjacency matrices that are incredibly
useful for working with directed graphs.
OVERVIEW OF ROUTINES
creating your own bitmaps:
BitMap* NewBitMap(short width, short height);
void KillBitMap(BitMap* bits);
rotating a bitmap image 90 degrees to the left or to the right:
BitMap* RotateRight(BitMap* bits);
BitMap* RotateLeft(BitMap* bits);
flipping a bitmap image horizontally or vertically:
BitMap* FlipVertical(BitMap* bits);
BitMap* FlipHorizontal(BitMap* bits);
rotating a bitmap image to a particular angle:
BitMap* RotateBitMap(BitMap* bits, short cx, short cy, Fixed angle);
duplicating a bitmap:
BitMap* DuplicateBitMap(BitMap* bits);
the paint bucket function:
BitMap* PaintBucketBitMap(BitMap* bits, short h, short v);
the lasso function:
BitMap* LassoBitMap(BitMap* bits);
the trace edges function:
BitMap* TraceBitMap(BitMap* bits);
transfer functions for converting to and from the PICT format:
BitMap* PICTToBitMap(PicHandle pic);
PicHandle BitMapToPICT(BitMap* bits);
logical operations on bitmaps:
BitMap* BitMapAND(BitMap* a, BitMap* b);
BitMap* BitMapOR(BitMap* a, BitMap* b);
BitMap* BitMapXOR(BitMap* a, BitMap* b);
BitMap* BitMapNOT(BitMap* a);
comparison:
Boolean EqualBitMaps(BitMap* a, BitMap* b);
pixel oriented functions:
Boolean BitMapTest(BitMap* bits, short h, short v);
void BitMapSet(BitMap* bits, short h, short v);
void BitMapClear(BitMap* bits, short h, short v);
Boolean BitMapToggle(BitMap* bits, short h, short v);
routines for drawing into bitmaps:
BitMapPort* NewBMP(BitMap* bits);
void DisposeBMP(BitMapPort* bmp);
#define WithBitMap(bits, bmp)
routines for copying bitmap data:
void PlotBitMap(BitMap* bits, short h, short v);
a routine for converting pascal strings into bitmaps:
BitMap* StringToBitMap(short font, short size, short face, StringPtr s);
SPECIFIC ROUTINE DESCRIPTIONS
NewBitMap
formal declaration:
BitMap* NewBitMap(short width, short height);
arguments:
width the width of the requested bitmap
height the height of the requested bitmap
return value:
a pointer to a Bitmap data structure.
if an error occurs, NULL is returned.
description:
NewBitMap creates a new bitmap pointer with the requested
dimensions. The raster data is initialized to zeros, and if
there is not enough memory to allocate the bitmap, NewBitMap
will return NULL.
example application:
The following creates a new bitmap pointer 100 pixels wide
and 200 pixels tall.
{ BitMap *the_bits;
the_bits = NewBitMap(100, 200);
...
notes:
You can call DisposePtr to dispose of a bitmap pointer created by
NewBitMap. The routine KillBitMap calls DisposePtr.
KillBitMap
formal declaration:
void KillBitMap(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
none.
description:
KillBitMap disposes of a bitmap pointer allocated by one of:
NewMacPaintBitMap, NewBitMap, RotateRight, RotateLeft, FlipVertical,
FlipHorizontal, RotateBitMap, DuplicateBitMap, PaintBucketBitMap,
LassoBitMap, PICTToBitMap, BitMapAND, BitMapOR, BitMapXOR, or BitMapNOT.
It's your general all purpose bitmap pointer disposal function.
example application:
The following creates a new bitmap pointer 100 pixels wide
and 200 pixels tall and then disposes of it by calling KillBitMap.
{ BitMap *the_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
KillBitMap(the_bits);
}
notes:
KillBitMap simply calls DisposePtr.
RotateRight
formal declaration:
BitMap* RotateRight(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated 90 degrees
to the right.
if an error occurs, RotateRight will return the value NULL.
description:
RotateRight creates a new bitmap containing the image
stored in the parameter bitmap pointer rotated 90 degrees
to the right. The resulting bitmap is appropriately sized:
i.e. if the source bitmap is 100 pixels wide and 200 pixels tall,
then the result bitmap pointer will be 200 pixels wide and 100
pixels tall.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 90 degrees to the right
before copying the image to the current grafport.
{ BitMap *the_bits;
BitMap *rotated_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
rotated_bits = RotateRight(the_bits);
if (rotated_bits != NULL) {
bounds = (*rotated_bits)->bounds;
PlotMap(rotated_bits, 0, 0, srcCopy);
KillBitMap(rotated_bits);
}
KillBitMap(the_bits);
}
notes:
RotateRight takes advantage of certain addressing and indexing
possibilities offered by the arrangement of the raster data
in memory. It is faster than calling RotateBitMap and specifying
a 90 degree angle.
RotateLeft
formal declaration:
BitMap* RotateLeft(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated 90 degrees
to the left.
if an error occurs, RotateLeft will return the value NULL.
description:
RotateLeft creates a new bitmap containing the image
stored in the parameter bitmap pointer rotated 90 degrees
to the left. The resulting bitmap is appropriately sized:
i.e. if the source bitmap is 100 pixels wide and 200 pixels tall,
then the result bitmap pointer will be 200 pixels wide and 100
pixels tall.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 90 degrees to the left
before copying the image to the current grafport.
{ BitMap *the_bits;
BitMap *rotated_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
rotated_bits = RotateLeft(the_bits);
if (rotated_bits != NULL) {
bounds = (*rotated_bits)->bounds;
PlotMap(rotated_bits, 0, 0, srcCopy);
KillBitMap(rotated_bits);
}
KillBitMap(the_bits);
}
notes:
RotateLeft takes advantage of certain addressing and indexing
possibilities offered by the arrangement of the raster data
in memory. It is faster than calling RotateBitMap and specifying
a -90 degree angle.
FlipVertical
formal declaration:
BitMap* FlipVertical(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter flipped upside down.
if an error occurs, FlipVertical will return the value NULL.
description:
FlipVertical creates a new bitmap containing the image
stored in the parameter bitmap pointer flipped upside
down. The resulting bitmap will be the same size as
the original image.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap flipped upside down before
copying the new flipped image to the current grafport.
{ BitMap *the_bits;
BitMap *flippin_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
flippin_bits = FlipVertical(the_bits);
if (flippin_bits != NULL) {
bounds = (*flippin_bits)->bounds;
PlotMap(flippin_bits, 0, 0, srcCopy);
KillBitMap(flippin_bits);
}
KillBitMap(the_bits);
}
notes:
none.
FlipHorizontal
formal declaration:
BitMap* FlipHorizontal(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter flipped horizontally.
if an error occurs, FlipHorizontal will return the value NULL.
description:
FlipHorizontal creates a new bitmap containing the image
stored in the parameter bitmap pointer flipped horizontally.
The resulting bitmap will be the same size as the original image.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap flipped horizontally before
copying the new flipped image to the current grafport.
{ BitMap *the_bits;
BitMap *flippin_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
flippin_bits = FlipHorizontal(the_bits);
if (flippin_bits != NULL) {
bounds = (*flippin_bits)->bounds;
PlotMap(flippin_bits, 0, 0, srcCopy);
KillBitMap(flippin_bits);
}
KillBitMap(the_bits);
}
notes:
none.
RotateBitMap
formal declaration:
BitMap* RotateBitMap(BitMap* bits, short cx, short cy, float angle);
arguments:
bits a bitmap pointer
cx the horizontal center of rotation
cy the vertical center of rotation
angle the angle (in degrees) to rotate the image. both positive
and negative values are ok. This is a floating point number.
return value:
a newly created bitmap pointer containing the image
from the bitmap pointer parameter rotated around the center
cx and cy angle degrees.
if an error occurs, RotateBitMap will return the value NULL.
description:
RotateBitMap creates a new bitmap containing the image from
the parameter bitmap pointer rotated angle degrees about the
center (cx, cy). The resultant bitmap will have the same dimensions
as the parameter bitmap regardless of the angle specified.
example application:
The example creates a new bitmap pointer containing the image
stored in the original bitmap rotated 35.5 degrees to the right
before copying the rotated image to the current grafport.
{ BitMap *the_bits;
BitMap *round_bits;
Rect bounds;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here we would draw something into the_bits */
round_bits = RotateBitMap(the_bits, 50, 100, 35.5);
if (round_bits != NULL) {
bounds = (*round_bits)->bounds;
PlotMap(round_bits, 0, 0, srcCopy);
KillBitMap(round_bits);
}
KillBitMap(the_bits);
}
notes:
The 68k implementation of RotateBitMap has a speedy implementation
built on top of the fixed math routines. For more information
about fixed math refer to the Mathematical and Logical Utilities
chapter of Inside Macintosh: Operating System Utilities.
DuplicateBitMap
formal declaration:
BitMap* DuplicateBitMap(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing an
exact duplicate of the bitmap parameter.
if an error occurs, DuplicateBitMap will return the value NULL.
description:
DuplicateBitMap creates a copy of the bitmap parameter.
example application:
In this example, we make a new bitmap, duplicate it, and then
dispose of the resulting bitmaps.
{ BitMap *the_bits;
BitMap *other_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
other_bits = DuplicateBitMap(the_bits);
if (other_bits != NULL) {
KillBitMap(other_bits);
}
KillBitMap(the_bits);
}
notes:
none.
PaintBucketBitMap
formal declaration:
BitMap* PaintBucketBitMap(BitMap* bits, short h, short v);
arguments:
bits a bitmap pointer
h the horizontal position to start painting
v the vertical position to start painting
return value:
a newly created bitmap pointer containing an ones in every
pixel where paint would not leak out starting from the point
(h, v).
if an error occurs, PaintBucketBitMap will return the value NULL.
description:
PaintBucketBitMap works like the paint bucket tool found in
most graphical applications. It calls the routine SeedFill
and to fill in the image information in the resulting bitmap
pointer.
example application:
In this example, we make a new bitmap and create a mask bitmap
using the PaintBucketBitMap routine starting at the point (50,50).
{ BitMap *the_bits;
BitMap *paint_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here, we would normally draw something in the bitmap */
paint_bits = PaintBucketBitMap(the_bits, 50, 50);
if (paint_bits != NULL) {
KillBitMap(paint_bits);
}
KillBitMap(the_bits);
}
notes:
PaintBucketBitMap calls SeedFill. For further information about
SeedFill refer to page 3-109 in the QuickDraw Drawing chapter of
Inside Macintosh: Imaging With QuickDraw.
LassoBitMap
formal declaration:
BitMap* LassoBitMap(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing an ones in every
pixel where paint would not leak in from the edges of the
bitmap.
if an error occurs, LassoBitMap will return the value NULL.
description:
LassoBitMap works like the lasso bucket tool found in
most graphical applications. It calls the routine CalcMask
and to fill in the image information in the resulting bitmap
pointer.
example application:
In this example, we make a new bitmap and create a mask bitmap
using the LassoBitMap routine.
{ BitMap *the_bits;
BitMap *paint_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here, we would normally draw something in the bitmap */
paint_bits = LassoBitMap(the_bits);
if (paint_bits != NULL) {
KillBitMap(paint_bits);
}
KillBitMap(the_bits);
}
notes:
LassoBitMap calls CalcMask. For further information about
CalcMask refer to page 3-111 in the QuickDraw Drawing chapter of
Inside Macintosh: Imaging With QuickDraw.
TraceBitMap
formal declaration:
BitMap* TraceBitMap(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a newly created bitmap pointer containing containing the original
image with the edges traced.
if an error occurs, TraceBitMap will return the value NULL.
description:
TraceBitMap performs the 'trace edges' command found in
many graphical applications returning a new bitmap
containing the traced image..
example application:
In this example, we make a new bitmap and create a new bitmap
containing the traced image.
{ BitMap *the_bits;
BitMap *traced_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
/* here, we would normally draw something in the bitmap */
traced_bits = TraceBitMap(the_bits);
if (traced_bits != NULL) {
KillBitMap(traced_bits);
}
KillBitMap(the_bits);
}
notes:
none.
EqualBitMaps
formal declaration:
Boolean EqualBitMaps(BitMap* a, BitMap* b);
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
true or false.
description:
returns true if the two bitmaps are the same size and
contain the same image content. returns false if either
bitmap is NULL.
example application:
In this example, we make a new bitmap and create a two bitmaps
and compare them by calling EqualBitMaps.
{ BitMap *the_bits;
BitMap *other_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
other_bits = TraceBitMap(the_bits);
if (other_bits != NULL) {
/* here, we would normally draw something in the bitmaps */
if (EqualBitMaps(other_bits, the_bits)) {
/* they're the same *blink* */
}
KillBitMap(other_bits);
}
KillBitMap(the_bits);
}
notes:
EqualBitMaps takes into account that either bitmap may have
different rowBytes values, and the possibility that garbage
values may be stored in the unused bits off to the right
of the boundary rectangle.
PICTToBitMap
formal declaration:
BitMap* PICTToBitMap(PicHandle pic);
arguments:
pic a handle to a QuickDraw picture
return value:
a newly created bitmap pointer containing a black and white
representation of the image drawn by the quickdraw picture
parameter.
if an error occurs, PICTToBitMap will return the value NULL.
description:
PICTToBitMap creates a new bitmap pointer the using the size
information provided in the QuickDraw picture pointer parameter
and draws the picture in the bitmap before returning the bitmap.
example application:
In this example, we call GetPicture to retrieve a picture from
a resource file and then we convert it to a bitmap by calling
the routine PICTToBitMap.
{ PicHandle the_picture;
BitMap *the_bits;
the_picture = GetPicture(128);
if (the_picture != NULL) {
the_bits = PICTToBitMap(the_picture);
if (the_bits != NULL) {
/* at this point, the the_bits contains the picture */
KillBitMap(the_bits);
}
}
notes:
none.
BitMapToPICT
formal declaration:
PicHandle BitMapToPICT(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a handle to a QuickDraw picture.
if an error occurs, the picture's picFrame will be
an empty rectangle.
description:
BitMapToPICT returns a QuickDraw picture that will draw the
image stored in the bitmap. BitMapToPICT is the inverse
of PICTToBitMap.
example application:
In this example, we create a bitmap and convert it into a QuickDraw
picture.
{ PicHandle the_picture;
BitMap *the_bits;
the_bits = NewBitMap(100, 200);
if (the_bits != NULL) {
the_picture = BitMapToPICT(the_bits);
KillBitMap(the_bits);
}
notes:
QuickDraw pictures are a good way to store image data.
BitMapAND
formal declaration:
BitMap* BitMapAND(BitMap* a, BitMap* b);
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of ANDing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
BitMapAND logically ANDs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and AND them together creating
a third bitmap.
{ BitMap *a=NULL, *b=NULL, *c=NULL;
a = NewBitMap(100, 100);
if (a == NULL) goto my_error_handler;
b = NewBitMap(100, 100);
if (b == NULL) goto my_error_handler;
c = BitMapAND(a, b);
if (c == NULL) goto my_error_handler;
/* at this point, c contains the result of logically ANDing
the bitmaps a and b */
my_error_handler:
if (a != NULL) KillBitMap(a);
if (b != NULL) KillBitMap(b);
if (c != NULL) KillBitMap(c);
}
notes:
useful for calculating the intersection of two sets of bits.
BitMapOR
formal declaration:
BitMap* BitMapOR(BitMap* a, BitMap* b);
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of ORing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
BitMapOR logically ORs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and OR them together creating
a third bitmap.
{ BitMap *a=NULL, *b=NULL, *c=NULL;
a = NewBitMap(100, 100);
if (a == NULL) goto my_error_handler;
b = NewBitMap(100, 100);
if (b == NULL) goto my_error_handler;
c = BitMapOR(a, b);
if (c == NULL) goto my_error_handler;
/* at this point, c contains the result of logically ORing
the bitmaps a and b */
my_error_handler:
if (a != NULL) KillBitMap(a);
if (b != NULL) KillBitMap(b);
if (c != NULL) KillBitMap(c);
}
notes:
useful for calculating the union of two sets of bits.
BitMapXOR
formal declaration:
BitMap* BitMapXOR(BitMap* a, BitMap* b);
arguments:
a a bitmap pointer
b a bitmap pointer
return value:
a bitmap pointer containing the logical result of XORing the
raster data from bitmap a with the raster data from bitmap b.
if an error occurs, NULL is returned.
description:
BitMapXOR logically XORs the raster data of two bitmap pointers
returning a new bitmap pointer containing the result. The two
parameter bitmaps must have identical dimensions.
example application:
In this example, we create two bitmaps and XOR them together creating
a third bitmap.
{ BitMap *a=NULL, *b=NULL, *c=NULL;
a = NewBitMap(100, 100);
if (a == NULL) goto my_error_handler;
b = NewBitMap(100, 100);
if (b == NULL) goto my_error_handler;
c = BitMapXOR(a, b);
if (c == NULL) goto my_error_handler;
/* at this point, c contains the result of logically XORing
the bitmaps a and b */
my_error_handler:
if (a != NULL) KillBitMap(a);
if (b != NULL) KillBitMap(b);
if (c != NULL) KillBitMap(c);
}
notes:
useful for calculating the difference of two sets of bits.
BitMapNOT
formal declaration:
BitMap* BitMapNOT(BitMap* a);
arguments:
a a bitmap pointer
return value:
a bitmap pointer containing the logical result of complementing the
raster data from bitmap a.
if an error occurs, NULL is returned.
description:
BitMapNOT returns a new bitmap pointer containing the inverse
of the raster image contained in the bitmap pointer a.
example application:
In this example, we create a bitmap and it's complement.
{ BitMap *a=NULL, *b=NULL;
a = NewBitMap(100, 100);
if (a == NULL) goto my_error_handler;
b = BitMapNOT(a);
if (b == NULL) goto my_error_handler;
/* at this point, b contains the compliment of a */
my_error_handler:
if (a != NULL) KillBitMap(a);
if (b != NULL) KillBitMap(b);
}
notes:
useful for calculating the complement of a set of bits.
BitMapTest
formal declaration:
Boolean BitMapTest(BitMap* bits, short h, short v);
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to test
v the vertical position of the pixel to test
return value:
true if the pixel is 1, false if the pixel is 0.
description:
BitMapTest tests the value of the pixel at the location (h,v)
returning true if the pixel is 1, and false if the pixel
is zero.
example application:
In this example, we create a bitmap and test the pixel
located at (25, 32).
{ BitMap *bits=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
....
if (BitMapTest(bits, 25, 32)) {
/* the pixel is 1 */
} else {
/* the pixel is 0 */
}
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
attempting to test a point outside of the bitmap's bounds
will produce unpredictable results.
BitMapSet
formal declaration:
void BitMapSet(BitMap* bits, short h, short v);
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
none.
description:
BitMapSet sets the value of the pixel at the location (h,v) to 1.
example application:
In this example, we create a bitmap and set the pixel
located at (25, 32) to the value 1.
{ BitMap *bits=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
....
BitMapSet(bits, 25, 32);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
attempting to set a pixel outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
BitMapClear
formal declaration:
void BitMapClear(BitMap* bits, short h, short v);
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
none.
description:
BitMapClear clears the value of the pixel at the location (h,v)
to 0.
example application:
In this example, we create a bitmap and set the pixel
located at (25, 32) to the value 0.
{ BitMap *bits=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
....
BitMapClear(bits, 25, 32);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
attempting to clear a pixel outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
BitMapToggle
formal declaration:
Boolean BitMapToggle(BitMap* bits, short h, short v);
arguments:
bits a bitmap pointer
h the horizontal position of the pixel to set
v the vertical position of the pixel to set
return value:
a boolean value indicating the state of the pixel
after the toggle operation. i.e. if the pixel is
set to the value 1, true is returned. If the pixel
is set to the value 0, false is returned.
description:
BitMapToggle inverts the value of the pixel at the location (h,v)
returning true if the pixel is set to 1 or false if the pixel
is set to 0.
example application:
In this example, we create a bitmap and invert the pixel
located at (25, 32).
{ BitMap *bits=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
....
BitMapToggle(bits, 25, 32);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
attempting to toggle a pixel outside of the bitmap's bounds
will produce unpredictable results and may even crash your
computer by overwriting something important like the operating
system or your program or something like that.
NewBMP
formal declaration:
BitMapPort* NewBMP(BitMap* bits);
arguments:
bits a bitmap pointer
return value:
a pointer to a BitMapPort data structure.
if an error occurs, NULL is returned.
description:
NewBMP is called by the WithBitMap macro and you should
never have to call it directly yourself. What it does is
it saves the original grafport, and creates a new grafport
suitable for drawing into the bitmap. NewBMP should be
followed by a call to DisposeBMP which will restore the
original grafport, and dispose of the grafport that was
created by NewBMP.
example application:
In this example, we create a bitmap and use the NewBMP to make
a grafport. Then we draw into it and call DisposeBMP to deallocate
the grafport.
{ BitMap *bits=NULL;
BitMapPort *bmp=NULL;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
bmp = NewBMP(bits);
if (bmp == NULL) goto my_error_handler;
/* after NewBMP, the grafport is set to draw into the bitmap */
MoveTo(10,10);
LineTo(20,20);
DrawString("\pHello World");
my_error_handler:
if (bmp != NULL) DisposeBMP(bmp);
if (bits != NULL) KillBitMap(bits);
}
notes:
if NewBMP returns a pointer to a BitMapPort, then you must
dispose of that pointer with a call to DisposeBMP.
DisposeBMP
formal declaration:
void DisposeBMP(BitMapPort* bmp);
arguments:
bmp a pointer to a BitMapPort structure allocated by NewBMP
return value:
none.
description:
DisposeBMP restores the original grafport and, deallocates
the grafport allocated for drawing into the bitmap.
The macro WithBitMap calls this routine automatically and you will
not normally have to call it directly.
example application:
see the example in NewBMP.
notes:
none.
WithBitMap
formal declaration:
MACRO WithBitMap(bits, bmp) { statement... }
arguments:
bits a bitmap pointer
bmp a variable you have declared of type BitMapPort*
return value:
not applicable
description:
WithBitMap is a macro facility that sets up the drawing
environment such that any drawing commands in the statement
following the macro instantiation will draw into the bitmap
provided as the first parameter.
example application:
In this example, we create a bitmap and use the WithBitMap
macro to do some drawing in it.
{ BitMap *bits=NULL;
BitMapPort *bmp;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
WithBitMap(bits, bmp) {
MoveTo(10,10);
TextFont(geneva);
TextSize(12);
DrawString("\pHello World");
}
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
none.
PlotBitMap
formal declaration:
void PlotBitMap(BitMap* bits, short h, short v);
arguments:
bits a bitmap pointer
h the horizontal location where the bitmap is drawn
v the horizontal location where the bitmap is drawn
mode transfer mode passed to copybits
return value:
none.
description:
PlotBitMap provides a simple interface for drawing a bitmap in
the current grafport. The bitmap is drawn with the top left corner
aligned with the point (h,v) using the indicated transfer mode.
example application:
In this example, we create a bitmap and use the WithBitMap
macro to do some drawing in it, and then we copy the result
to the current grafport at the location (75, 23) using the
PlotBitMap routine.
{ BitMap *bits=NULL;
BitMapPort *bmp;
bits = NewBitMap(100, 100);
if (bits == NULL) goto my_error_handler;
WithBitMap(bits, bmp) {
MoveTo(10,10);
TextFont(geneva);
TextSize(12);
DrawString("\pHello World");
}
PlotBitMap(bits, 75, 23, srcCopy);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
}
notes:
PlotBitMap calls CopyBits.
StringToBitMap
formal declaration:
BitMap* StringToBitMap(short font, short size, short face, StringPtr s);
arguments:
font a font number
size the font size
face the font style
(normal,bold,italic,underline,outline,shadow,condense,extend)
s a pointer to a pascal string
return value:
a bitmap pointer
description:
StringToBitMap converts the string pointed to by s into a bitmap
drawing the string onto an appropriately sized bitmap for the
given font, size, and style(face). StringToBitMap is useful for
converting strings to bitmap so rotation can be applied with
RotateRight or RotateLeft before it is displayed. StringToBitMap
preserves the current grafport.
example application:
In this example, we create a bitmap pointer containing
the string "\pHello World" (using bold, underlined,
24 point geneva font), rotate it 90 degrees to the
right, and draw the result in the current grafport
at the location (110,34) using the PlotBitMap routine.
{ BitMap *bits = NULL, *right_bits = NULL;
bits = StringToBitMap(geneva, 24, bold + underlined, "\pHello World");
if (bits == NULL) goto my_error_handler;
right_bits = RotateRight(bits);
if (right_bits == NULL) goto my_error_handler;
PlotBitMap(right_bits, 110, 34);
my_error_handler:
if (bits != NULL) KillBitMap(bits);
if (right_bits != NULL) KillBitMap(right_bits);
}
notes:
none.
file BitMap.txt Copyright (C) 1996 by John Montbriand. All Rights Reserved.
end of file
